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1 KidCode® Application Programming Interface (API) w ^ 

2 • **** 



3 

4 This API defines the data and function calls that are used for communication between the 

5 KidCode Main Email program and installable components. Each installable component can u 

6 be one of two types: ^ 

7 • mailbox browser/editor component 

8 • message authoring/display component 

10 KidCode Main Email application may communicate with another mail server such as an 

11 SMTP compliant server to retrieve and store email messages. Alternatively, the Email Main 

1 2 program may include code for many of the functions normally associated with a mail server 

1 3 program. Whether in conjunction with a mail server, or on its own, the Email Main program 

14 handles all functions associated with sending and receiving email messages. This includes 

15 reading and writing mailbox files to/from permanent storage or other mail servers on a 

16 network (e.g. using POP3), finding and verifying network addresses, and sending mail 

1 7 messages to other servers on a network. 
18 

19 The Main Email Program also provides a GUI that provides interaction with a user for those 

20 functions that are directly associated with storage and transfer of electronic mail messages and 

2 1 mailboxes. In particular, the Main Email program includes buttons and/or menu items that 

22 allow a user to: 

23 • Send (a message), 

24 • Reply (to a message), 

25 • Open (a message or a mailbox), 

26 • Delete/Trash (messages or mailboxes), 

27 • Save (a message to an alternative mailbox) 

28 • Print (a message) 
29 

30 The Main Email Program also handles all data bundling and unbundling that may be 

l\ x^r Uired t0 transform the message data used by a message authoring component into a fully 

32 MIME compliant message type. This way each message authoring component can handle 

33 data in a format most convenient to it and all MIME parsing and details associated with 

34 protocol compliance can be centralized in the Main Email application. The only requirement 

35 for the message data passed between a message authoring component and the Main Email 

36 Program is that the message body data be formatted either as an ASCII string or in a binhex 

37 format. 
38 

39 The KidCode Main Email program communicates with installable components in order to 

40 execute the commands defined above. 
41 

4 2 Mailbox browser/editor components 

43 Mailbox components are used to display, edit, and browse mailboxes. Different kinds of 

44 users and different types of messaging applications (e.g. fax, traditional email, internet voice) 

45 may require very different displays and functionality from a mailbox viewer/editor. 

46 Installable mailbox components make it possible to upgrade, select from multiple viewing 

47 formats, utilize different mailbox viewer/editors for different users, and in general increase the 

48 range of functionality that can be achieved within one basic messaging application program. 

50 Message authoring/display components 

51 Message handler components make it possible to handle an unlimited number of message 

52 types. Each message handler component is designed to deal with a specific MIME type of 

53 message. The MIME data standard has been designed so that application developers can 

54 define new MIME types as needed by labeling these with the "/application-x" prefix. A 

55 message handler component can be any program that defines a message MIME type of data 
^7 ti? 1 U hand ! es and that implements the callback entry points described in this document. 

57 These functions allow the Main Email application to obtain information about the message 

58 handler and allows the message handler to respond to standard mail commands such as Send 
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60 
61 
62 
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65 
66 
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or Reply, that have been issued by a user through the Main Email interface. Example message 
handler components included in the KidCode application are an ordinary ascii text message 
handler, a game called Rebus that allows users to create and respond to graphical rebus 
messages, an a sample mathematics workbook that allows students and a teacher to send 
workbook problems to one another. 

Global variable naming conventions: 

Each movie should name its global variables with a prefix that identifies the movie and a 
capital G for global". We will keep track of each movie's prefix. For now we have the 
following identifing prefixes: 



72 



mmmMmmmmmmmmm 






em_ 


main movie 


emG_ 


tm_ 


text movie 


tmG_ 


rm_ 


rebus movie 


rmG j 


cm_ 


connect movie 


cmG_ 


tgm_ 


text grid movie 


tgmG_ 


pm_ 


puzzle movie 


pmG_ 


mbx_ 


mailbox movie j 


mbxG_ 
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Main Movie Public Data Types 

em_ComponentType symbol = #mailbox or #msgHandler 
em_UserName string 
em_UserData struct ( 



) 



str 
str 
str 

em_AddressBook 
em_MailboxList 

str 

str 

str 



UserName 
FullName 

ReturnAddress 
AddressBook 
Mailboxes 
SMTPHost 
POP3Host 
Password 



em_MailboxName string 

em_Mailbox struct ( 

em_mailboxName boxName 
list of emMailData 

) 

em_RegisteredUsers list of em_UserName 



em_MailData struct ( 
em_Address 
em_Address 
str 
str 
str 
list 

) 



To 
From 
Re 
Data 

MimeType 
MsgBody 



em_MessageNumber int 
em_Mode symbol = #author or #display 
em_Component!nfo struct ( 



str 
int 

em_ComponentType 
str 

) 



ComponentName 

ComponentID 

ComponentType 

ComponentMIMEType ; nil if mailbox 
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1 2 1 Email Main API Functions 

122 

123 These functions are called by the installable components to access services provided in the 

124 KidCode Main Email program. 
125 

126 

127 /********************************************** 

128 **/ 

129 /* emh_getUserMailbox 

130 Return a mailbox data structure for the current user and mailbox name. This function is 

131 normally called by a mailbox handling component. Mailbox handling components may use 
W\ temporary files to hold mailbox contents but they should never access the users mailbox files. 

133 All access to these files must be obtained through the Main Email program. 

134 */ 
135 

136 em_Mailbox emh_getUserMailbox ( 

137 em_MailBoxName 

138 ) 
139 
140 

141 /******************************************^ 

142 **/ 

143 /* emh_getUserData 

144 Return a data structure with user information. The KidCode Main Email program maintains 

145 all user information and handles user administration functions. The Main program also 

146 communication with external Mail servers which may contain other user information not part 

147 of the KidCode API. 

148 */ 
149 

150 em_UserData emh_getUserData ( 

151 em_UserName, 

152 ) 
153 
154 

155 /********************************************** 

156 **/ 

157 /* emh_continue 

III H^ed by insta Hable components to explicitly pass control back to the Main Email program. 

159 This function is necessary for the Director/Lingo implementation. 

1 60 */ 
161 

162 void emh_continue ( 

163 em_ComponentType 

164 ) * 3V 
165 

166 
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167 /****************************************************** + * # + * s|I<1 

168 **/ 

169 /* emh_killComponent 

170 Used by an installable component to inform the Main Email program that it is preparing to 

171 terminate. This allows the Main program to free any memory and/or data structures that have 

172 been allocated to the component. 

173 */ 
174 

175 void emh_killComponent ( 

176 ) 
177 
178 

179 /************************************************************* 

180 **/ 

181 /* emh_passMessage 

J « u St A- P rimaril y bv mailbox components to pass a message to the Main program so that it can 

183 be displayed by the appropriate message handling component. Email main takes the message 

184 argument (em.MailData, looks up the Mimetype of the message, and invokes the appropriate 

185 message handler to display the message. 

186 */ 
187 

188 void emh_passMessage ( 

189 em_MailData, 

1 90 em_MessageNumber 

191 ) 
192 
193 

194 /******************************* ****************************** 

195 **/ 

196 /* emh_getMessage 

III R 5 tums the mes sage (em_MailData) with Number MessageNumber from the MailboxName 

198 of the current user. Can be used by installable components to retrieve specific messages from 

199 the user's mailboxes. " 
200 

20 1 If this is called with the messageNumber set to 0, email main assume the typeOrBoxName 

™5 a ^ gU !i r i ent IS a imm&t yP e and returns a new message structure. Message handling components 

IU3 should call emh_getMessage with the number set to 0 and the mimetype whenever a new 

205 5^ essa S e 1S started. Normally this should be done whenever an active message is trashed. 

206 

207 em_MailData emh_getMessage ( 

208 em_MessageNumber 

209 str typeOrBoxName 

210 ) 
211 
212 
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213 /*********************************^ 

214 **/ 

215 /* emh_getRegisteredUsers 

216 Returns a list of usernames for the users that are registered with the KidCode system, i.e. that 

217 have been added as users by the User Adminstration part of the Main Email Program. This is 

218 the same list of users that appear in the logon listbox when the program is started up. It may 

219 be used by installable components to create listboxes for filling address fields in messages or 

220 for checking on whether a particular address is external to the system. 

221 */ J 
222 

223 em_RegisteredUsers emh_getRegisteredUsers ( 

225 
226 

227 /******************************** 

228 **/ 

229 /* emh_sendMessage * 

230 Email Main sends the message argument (em_MailData) by either forwarding to an external 

231 mail server or, if it is a registered KidCode user, writing the message to the user's incoming 

232 mail mailbox. ^ & 

233 */ 
234 

235 void emh_sendMessage ( 

236 em_MailData 

237 ) 
238 
239 
240 

241 /********************************^ 

242 **/• 

243 /* emh_saveMessage 

244 Email Main saves the message argument (em_MailData) for the currently logged on user by 

245 writing the message to the user's "notes in progress" mail mailbox. 

246 */ 
247 

248 void emh_saveMessage ( 

249 em_MailData 

250 ) 
251 
252 
253 
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254 
255 **/ 



**/ 

256 /* emh_disableButton 

257 It is recommended that this function be used carefully. Normally Email Main controls the 

258 state of all the buttons available to users to access message handling of the main program (i.e 

259 buttons in the purple left hand panel). This function can be used to request that Email Main 

260 disable the button specified by the argument, ButtonName. If the button is disabled - whether 

261 it was already disabled or is disabled as a result of the function call - the function will return 

262 TRUE, otherwise it will return FALSE. The calling component should check on whether the 

263 function call succeeded and proceed accordingly. 

265 

266 em_Return Value emh_disableButton ( 

267 str ButtonName 

268 ) 
269 
270 
271 

272 /*****************************^ 

273 **/ 

274 /* emh_enableButton 

275 It is recommended that this function be used carefully. Normally Email Main controls the 

276 state of all the buttons available to users to access message handling of the main program (i.e. 

277 buttons in the purple left hand panel). This function can be used to request that Email Main 

278 enable the button specified by the argument, ButtonName. If the button is enabled - whether 

279 it was already disabled or is disabled as a result of the function call - the function will return 

280 TRUE, otherwise it will return FALSE. The calling component should check on whether the 

281 function call succeeded and proceed accordingly. 

283 

284 em_Return Value emh_enableButton ( 

285 str ButtonName 

286 ) 
287 
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288 API Functions Required Implementation of all Component Types 

289 
290 

291 /******************** ***************************************** 

292 **/ 

293 /* emc.startMeUp 

294 Used by Email Main to tell an installable component to start. This function will execute prior 

295 to initialization of the component's data structures. Which should only be intialized after the 

296 component receives the emc_initWindow call from Email Main. 
298 */" S funCtion is necessar y for the Director/Lingo implementation. 
299 

300 em_Return Value emc startMeUp ( 

301 ) ~ 
302 

303 

304 /************************************************************* 

305 **/ 

306 /* emc_init Window 

307 Used by Email Main to tell an installable component to initialize it's data structures and 

308 prepare its graphical display. The component is passed the username of the current user. If 

309 it requires additional user information in order to initialize, it can call emh_getUserInfo 

310 within it's implementation of this function. 

311 */ 
312 

3 1 3 em_Return Value emc_initWindow ( 

314 em_UserName 

315 ) 
316 
317 

318 /**************************************************** ********* 

319 **/ 

320 /* emc_closeWindow 

321 Used by Email Main to tell an installable component to free all memory that it has used, close 

322 it s window, and shut down. 

323 */ 
324 

325 em_Return Value emc closeWindow ( 

326 ) " ' 
327 

328 

329 /************************************************************* 

330 **/ 

331 /* emc_getComponentInfo 

y sed b y Email Main t0 S et required information such as componentName, componentID, etc. 

333 from the installable component. 

334 */ 
335 

336 em_ComponentInfo emc_getComponentInfo ( 

338 
339 

340 API Functions required of a Mailbox Handler Component 

342 

343 /************************************************************* 

344 **/ 

345 /* mbx_getMessageNumbers 
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346 Used by Email Main to get the message number of the currently selected message in the 

347 mailbox browser. If no message is selected, the list should be emptv 

348 */ 
349 

350 list of int mbx_getMessageNumbers ( 

352 
353 

354 /******************************** 

355 **/ 

356 /* mbx_getMessage 

357 Used by Email Main to get the message data structure of the message with 

358 emJVIessageNumber from the mailbox currently displayed in the mailbox browser. If the 

359 function fails, e.g. if there is no message with the given message number, the function returns 

360 an empty list. 

361 */ 
362 

363 em_MailData mbx_getMessage ( 

364 em_MessageNumber 

365 ) 
366 
367 

368 /******************************** 

369 **/ 

370 /* mbx_trashMessages 

371 Used by Email Main to tell the mailbox component to update it's display and it's data 

372 structures to delete messages with messageNumbers in the argument list. If the function fails, 
In a e ' 8 * if ° ne ° f the messa S e numb ers is invalid, the function returns FALSE, otherwise it returns 
374 TRUE. This function should be implemented so that it does not perform partial deletes, i.e. 

Vn\ *l ther 11 succeeds in deleting all of the messages in the list or it should not delete any message. 

376 */ 

377 

378 em_Return Value mbx_trashMessages ( 

379 list of em_MessageNumber 

380 ) 
381 
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382 /*********************************************^ 

383 **/ 

384 /* mbx_openMailbox 

385 Used by Email Main to tell the mailbox component to display the mailbox passed in the 

386 argument. 

387 */ 
388 

389 em_Return Value mbx_openMailbox ( 

390 em_Mailbox 

391 ) 
392 
393 
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394 Functions required of a Message Handler Component 

396 
397 
398 

399 /* msh_sendMessage 

400 Used by Email Main to tell a message handling component to pass back a fully completed 

401 message data structure so that it can be sent to the recipient specified in the message's address 

402 field. The message handling component should update it's display as appropriate for a 

403 message that has been sent. It should also change it's state to #display mode because a 

404 message that has already been sent should not be editable. If the function fails, e.g. if a fully 

405 completed message cannot be constructed (for example, if the user has not specified a 

406 message recipient), the function returns an empty list. 
407 

408 The message handling component will normally control all dialogs with a user that pertain to 

409 the message under construction. For example to alert the user to the fact that a message 

410 recipient is required. However, if the message handling component fails to pass back a 

411 properly formatted, completed message data structure, (or an empty list acknowledging 

412 failure) Email Main will detect the error and alert the user about the field or fields that have 

413 not been specified. 

414 */ 
415 

416 em_MailData msh_sendMessage ( 

417 ) 
418 
419 

420 /*****************************^ 

421 **/ 

422 /* msh_openMessage 

423 Used by Email Main to pass a message data structure to a message handling component so 

424 that it can be displayed. The message handling component should display the message in the 

425 specified mode - either #author or #display. If the em_Mode argument is #display the 

426 message should not be editable. Otherwise the message should be opened so that it can be 

427 edited. 
428 

429 If the function fails, e.g. if an error is detected in the message body, the message handler 

430 returns FALSE, otherwise the message handler returns TRUE. 

431 */ 
432 

433 em_Re turn Value msh_openMessage ( 

434 em_MailData 

435 em_Mode 

436 ) 
437 
438 
439 
440 

441 /******************************^ 

442 **/ 

443 /* msh_rep!yMessage 

444 Used by Email Main to inform a message handling component to display the currently active 

445 message for editing as a reply. In order to reply the message handing component will 

446 generally create a new message with the mode set to #author. The new message body may 

447 contain material from the original message that is being replied to. In addition, message 

448 handling components that handle different player roles may enable or disable various role 

449 specific tools at this time. For example, the Rebus message handler will change the 

450 RebusState of the new message and enable guessboxes as appropriate. 
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452 If the function fails, e.g. if an error is detected in the message body, the message handler 

453 returns FALSE, otherwise the message handler returns TRUE. 

454 */ 
455 

456 em_Return Value msh_replyMessage ( 

457 ) 
458 
459 

460 /******************************^ 

461 **/ 

462 /* msh_clearMessage 

463 Used by Email Main to inform a message handling component that the current message 

464 should be cleared from the display and from the message handling component's data 

465 structures. This function is used, for example, when the user indicates they want to trash the 

466 current message by clicking on the "trash" button in the Email Main purple panel. 
467 

468 If the function fails, the message handler returns FALSE. Otherwise the message handler 

469 returns TRUE. 

470 */ 
471 

472 em_Return Value msh clearMessage ( 

473 ) 
474 
475 
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476 /*****************************^ 

477 **/ 

478 /* msh_printMessage 

479 Used by Email Main to inform a message handling component that a message should be 

480 printed. This function is used, for example, when the user indicates they want to print the 

481 current message by clicking on the "print" button in the Email Main purple panel. 

482 When the argument, em_maiiData, is an empty list, the message handler component should 

483 print the currently active message. Otherwise the message handler component should print 

484 the message argument. Normally, if the message handler component has been fully 

485 initialized and is displayed in a window, Email Main will call this function with an empty list 

486 for an argument. 
487 

488 The function may also be used by the Main Email program to have a message handler print a 

489 message even though the message handler component has not been fully initialized and 

490 displayed in a window. For example, this will occur if an active mailbox component receives 

491 a print request from Email Main for a message that has been selected in the mailbox browser. 

492 In this case, Email Main will send a request to the appropriate message handler component to 

493 print the message without fully starting it up and initializing its window. Therefore the 

494 message handler should implement the msh_printMessage function so that the following 

495 sequence of function calls succeeds - emc_startMeUp, msh_printMessage(message). 
496 

497 If the function fails, the message handler returns FALSE. Otherwise the message handler 

498 returns TRUE. 

499 */ 
500 

501 em Return Value msh_printMessage ( 

502 emJVlailData 

503 ) 
504 
505 



